©Copyright 1995 Rogue Wave Software
Because C++ is still a young language, there is no standard way to structure a reference manual for a class or group of classes. The reference is presented here as an alphabetical listing of classes, with their member and global functions grouped in categories according to their general use. The categories are not a part of the C++ language, but do provide a way of organizing the many functions.
Each class includes a brief description, an illustration showing its inheritance hierarchy, and a synopsis indicating the header file(s) associated with the class. The synopsis also shows a declaration and definition of a class object, and any type definitions that are used.
Member functions for each class are listed alphabetically. Member functions fall into three general types:
Throughout the documentation, there are frequent references to "self," which should be understood to mean "*this ".
RWDBExpr <--
RWDBAssignment
RWCollectable <--
#include <rw/db/expr.h>
RWDBAssignment is the result of applying the RWDBColumn::assign() method to an RWDBExpr. The result is an encapsulation of the SQL "SET column = expression" phrase, where column refers to the RWDBColumn instance whose assign() method produced the RWDBAssignment, and expression refers to its argument. RWDBAssignment's are only used to build RWDBUpdaters.
Return to Top of File.RWCollectable <-- RWDBBlob
#include <rw/db/blob.h> RWDBBlob b; // default; zero capacity and length RWDBBlob b(2048); RWDBBlob b(void* data, size_t len); RWDBBlob b(dataPtr, datasize);
Most database vendors supply one or more data types that can store binary data of any length ("Binary Large Objects," or "Blobs"). DBtools.h++ stores data of these types as RWDBBlob. RWDBBlob provides storage and rudimentary access to the binary data. Applications may wish to derive from RWDBBlob to add semantics to the data. This class is implemented using a technique called copy on write. With this technique, the copy constructor and assignment operators still reference the old object and hence are very fast. An actual copy is made only when a "write" is performed, that is if the object is about to be changed. The net result is excellent performance, but with easy-to-understand value semantics.
The member function putBytes() is used to populate an RWDBBlob. This method is safe and robust, but can be inconvenient in cases where large objects have already been loaded into memory. The constructor RWDBBlob(void* data, size_t length) is provided to allow applications to "wrap" existing data blocks in an RWDBBlob interface. Blobs built with this constructor do not manage the memory addressed by the data pointer; your application continues to be responsible for it.
RWDBBlob inherits from class RWCollectable. The virtual functions of the base class RWCollectable have been redefined.
Return to Top of File.#include <rw/db/column.h> RWDBColumn c = myTable["columnName"];
RWDBColumn provides a way to refer to a particular column of a table or schema, or to a particular parameter of a stored procedure. An application obtains instances of RWDBColumn by indexing into an RWDBTable or RWDBSchema.
RWDBColumn instances may be used in expressions (see RWDBExpr), which in turn are used to build up encapsulated SQL objects such as RWDBSelector and RWDBUpdater.
RWDBColumn instances are also used in RWDBSchema. An RWDBSchema is a collection of RWDBColumns used to describe a database table, view, or stored procedure. When used in this way, RWDBColumn stores several pieces of information:
DBtools.h++ does not obtain schema information until it is required. If no schema information has yet been obtained for the table containing a column, the column will contain default values.
RWDBColumn is designed around the Interface / Implementation paradigm. An RWDBColumn instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. Unlike many DBtools.h++ classes, RWDBColumn implementations do not require database-specific variants.
Return to Top of File. RWDBExpr <--
RWDBCollectableExpr
RWCollectable <--
#include <rw/db/expr.h>
RWDBCollectableExpr adds RWCollectable semantics to RWDBExpr. DBtools.h++ uses RWDBCollectableExpr internally to store lists of RWDBExprs. Applications requiring similar functionality can do the same.
Return to Top of File.RWDBTable <-- RWDBSelectorBase <-- RWDBCompoundSelector
#include <rw/db/comsel.h> RWDBSelector s1, s2; RWDBCompoundSelector cs = s1 + s2; RWDBCompoundSelector cs = s1 * s2 RWDBCompoundSelector cs = s1 - s2;
Instances of this class are created as the result of the set operators Union, Intersection, or Difference applied to RWDBSelector.
RWDBSelector and RWDBCompoundSelector share the common base class RWDBSelectorBase.
Return to Top of File.#include <rw/db/connect.h> RWDBConnection connection = myDataBase.connection();
Connections represent a scarce resource that applications can allocate and manage themselves. An RWDBConnection is an object that may be requested from an RWDBDatabase, and passed to many methods to specify that the method should use the existing open connection.
Operations requested without supplying a connection are performed using a connection invisibly supplied by RWDBDatabase. If none are available, an error results. Thus, the use of explicit connections eliminates one likely source of errors, at some cost in program complexity.
Each RWDBConnection knows which RWDBDatabase produced it, and each RWDBDatabase knows what connections it has produced.
RWDBConnection is designed around the Interface / Implementation paradigm. An RWDBConnection instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBConnection's implementation is a base class from which a family of database-specific connection implementations is derived.
Return to Top of File.#include <rw/db/func.h>
RWDBCritFormDefinition myFunc("myFormat");
RWDBCritFormDefinition is a base class for a family of classes that provide an extensible mechanism that an application can use to define functional notation for RWDBCriterion. RWDBCritFormDefinition allows a programmer to create an object that will translate into an RWDBCriterion and eventually be expanded into an SQL string. The object will allow up to four expressions to be embedded into the resultant string.
An RWDBCritFormDefinition object is instantiated with a format string. The format string may contain placeholders for up to four positional parameters, which are labeled "%0" through "%3." An object defined in this way may subsequently be referenced in the same way that pre-defined functions like rwdbMax and rwdbAvg are referenced.
When an RWDBCritFormDefinition object is expanded by an RWDBCriterion's asString() method, each instance of "%0" is replaced with the first actual argument, each instance of "%1" is replaced with the second actual argument, and so on. There can be multiple instances of a placeholder in the format string, and the place-holders may occur in any order. This allows great flexibility in defining functions, at the cost of losing compile-time checking on the number of arguments actually passed. To enable compile-time checking on number of actual arguments (at the cost of some flexibility), use the RWDBCritFuncDef<n> classes.
Return to Top of File.RWDBExpr <-- RWDBCriterion
#include <rw/db/expr.h>
RWDBCriterion is the result of applying logical operators to RWDBExpr. It is used to encapsulate SQL "WHERE" clauses.
RWDBCriterion represents a specialized type of RWDBExpr that will be evaluated in an SQL statement as a boolean value. RWDBCriterion adds neither components nor member functions to the base class. It provides a layer of type safety: a non-boolean expression cannot accidentally be placed in a context requiring a boolean.
Return to Top of File.RWDBCritFormDefinition <-- RWDBCritFuncDef<n>
#include <rw/db/func.h>
RWDBCritFuncDef0 myFunc0("myFunc0");
RWDBCritFuncDef1 myFunc1("myFunc1");
RWDBCritFuncDef2 myFunc2("myFunc2");
RWDBCritFuncDef3 myFunc3("myFunc3");
RWDBCritFuncDef4 myFunc4("myFunc4");
RWDBCritFuncDef0, RWDBCritFuncDef1, RWDBCritFuncDef2, RWDBCritFuncDef3 and RWDBCritFuncDef4 are specialization's of RWDBCritFormDefinition. They provide a simplified mechanism for defining SQL functions of 0 - 4 arguments, respectively. Unlike the base class, these classes do not require positional placeholders in their function definitions. Also, since the number of required arguments is fixed, compile-time checking can be done on the number of arguments actually passed.
Return to Top of File.#include <rw/db/cursor.h>
RWDBCursor cursor = myDbase.cursor(mySelector);
RWDBCursor cursor = myDbase.cursor("SQL String");
RWDBCursor cursor = myTable.cursor();
RWDBCursor is an encapsulation of a database cursor. RWDBCursor is a relatively low-level construct that maps directly onto a database cursor.
Despite the efforts of various standards bodies, cursor capabilities vary widely among database vendors. DBtools.h++ makes no attempt to emulate functionality that is not supported by the underlying database engine. For example, if a database vendor's implementation does not support scrollable cursors, an application requesting a scrollable RWDB Cursor from that RWDBDatabase will receive an RWDBCursor with a status of RWDBStatus::notSupported. The remainder of this section assumes that all features are supported. See the DBtools.h++ Access Library documentation for details concerning RWDBCursor restrictions for a particular database.
RWDBCursor captures common features of database cursors. Specifically:
The insertion operator (<<) is used to supply an RWDBCursor with pointers to application variables. When possible, RWDBCursor performs a cursor bind operation directly on the pointer provided. This is always possible for pointers to primitive C++ types. Otherwise, the RWDBCursor allocates enough space internally to do the required type conversion, binds to its internal buffers, and arranges for results to be copied into the buffers supplied by the application.
An application continues to own the memory supplied to an RWDBCursor, and it is the application's responsibility to ensure that a pointer remains valid for as long as the RWDBCursor requires it. The unbind() method can be used to disassociate program memory from the RWDBCursor.
RWDBCursor has a notion of the current column position within the current row. Each time the cursor is advanced to a new row, the column position is set to 0. Each insertion increments the column position by 1. The indexing operators ( [ ] ) set the position to a specified index, column, or column name. They return a reference to self, so that any of the following notations may be used:
cursor << &x;
cursor[i] << &x;
cursor["columnName"] << &x;
cursor[table["columnName"]] << &x;
RWDBCursor is designed around the Interface / Implementation paradigm. An RWDBCursor instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. RWDBCursor implementations are base classes from which a family of database-specific cursor implementations are derived.
Return to Top of File.#include <rw/db/dbase.h>
#include <rw/db/dbmgr.h>
RWDBDatabase dBase = RWDBManager::database("DbType", "Servername", "LoginName",
"PassWord", "DatabaseName", "Role");
RWDBDatabase manages connections with database servers. A database object represents a server, a user on that server, and a database opened for that user. Database objects are produced by the RWDBManager. RWDBDatabase provides an interface for tables, queries, direct SQL transactions, transaction control, and data definition language (DDL) concepts. RWDBDatabase is designed around the Interface / Implementation paradigm. An RWDBDatabase instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBDatabase's implementation is a base class from which a family of database-specific implementations is derived.
Every valid RWDBDatabase implementation has a database type. It might be a "SYBASE" database, or "ORACLE" database, for example. Applications request RWDBDatabases of a particular type by specifying the type to the RWDBManager; once a valid RWDBDatabase instance is obtained, its implementation type is transparent to the application. Objects produced by an RWDBDatabase instance automatically have the same implementation type as the producer. For example, an "INGRES" type RWDBDatabase automatically produces "INGRES" type RWDBTables.
Return to Top of File.#include <rw/db/datetime.h> RWDBDateTime now; // construct current date and time
RWDBDateTime represents a date, stored as a Julian day number, plus a time, stored as the number of milliseconds since midnight. The member function isValid() can be used to determine whether an RWDBDateTime is a valid date and time.
RWDBDateTime instances can be converted to and from RWDate and/or RW Time instances, and to and from the Standard C library type struct tm defined in <time.h>.
Output formatting is done using an RWLocale object. The default locale formats according to US conventions. See the Tools.h++ Reference Manual for further discussion of RWLocale
Note that because the default constructor for this class creates an instance holding the current date and time, constructing a large array of RWDBDateTime may be quite slow. If this is an issue, declare your arrays with a class derived from RWDBDateTime that provides a faster constructor.
Return to Top of File.#include <rw/decport.h> RWDecimalPortable dec; // construct a decimal == 0 dec = "1.23"; // construct a decimal == 1.23
RWDecimalPortable represents an arbitrary precision decimal fraction.
Return to Top of File.#include <rw/db/deleter.h> RWDBDeleter deleter = myTable.deleter();
RWDBDeleter is an encapsulation of an SQL "DELETE" statement.
RWDBDeleter's where() method is used to specify a "WHERE" clause. The "WHERE" clause is encapsulated by an RWDBCriterion, which is some number of RWDBExprs combined with logical operators.
A "DELETE" statement does not normally produce results. However, DBtools.h++ recognizes that some database vendors provide triggers, which can cause results to be generated by a "DELETE" statement. Consequently, RWDBDeleter's execute() method returns an RWDBResult, which is a sequence of zero or more RWDBResultTables . Applications are not obliged to request any tables from the returned object.
RWDBDeleter is designed around the Interface / Implementation paradigm. An RWDBDeleter instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBDeleter's implementation is a base class from which a family of database-specific deleter implementations is derived.
Return to Top of File.#include <rw/db/duration.h> RWDBDuration d; // construct zero length duration
RWDBDuration represents a time span, stored in a double as a number of seconds.
RWDBDuration supports arithmetic operations involving the imprecise quantities "months" and "years." As a reminder, the terms RWMonth and RWYear are used in some member function names. The following conversions are used:
#define RWDB_MILLISECONDS_PER_SEC ((double)1000.0) #define RWDB_SECONDS_PER_MIN ((double)60.0) #define RWDB_SECONDS_PER_HR (RWDB_SECONDS_PER_MIN * 60.0) #define RWDB_SECONDS_PER_DAY (RWDB_SECONDS_PER_HR * 24.0) #define RWDB_SECONDS_PER_WEEK (RWDB_SECONDS_PER_DAY * 7.0) #define RWDB_SECONDS_PER_RWMTH (RWDB_SECONDS_PER_WEEK * 4.0) #define RWDB_SECONDS_PER_RWYR (RWDB_SECONDS_PER_RWMTH * 12.0)
For example, adding 1 RWMonth to an RWDBDuration adds 4 weeks' worth of seconds to the duration, irrespective of the number of weeks in any particular month.
Return to Top of File.RWDBExprFormDefinition <-- RWDBExprFuncDef<n>
#include <rw/db/func.h>
RWDBExprFuncDef0 myFunc0("myFunc0");
RWDBExprFuncDef1 myFunc1("myFunc1");
RWDBExprFuncDef2 myFunc2("myFunc2");
RWDBExprFuncDef3 myFunc3("myFunc3");
RWDBExprFuncDef4 myFunc4("myFunc4");
RWDBExprFuncDef0, RWDBExprFuncDef1, RWDBExprFuncDef2, RWDBExprFuncDef3 and RWDBExprFuncDef4 are specialization's of RWDBExprFormDefinition. They provide a simplified mechanism for defining SQL functions of 0 - 4 arguments, respectively. Unlike the base class, these classes do not require positional placeholders in their function definitions. Also, since the number of required arguments is fixed, compile-time checking can be done on the number of arguments actually passed.
Return to Top of File.#include <rw/db/func.h>
RWDBExprFormDefinition myFunc("myFormat");
RWDBExprFormDefinition is a base class for a family of classes which provide an extensible mechanism for an application to define functional notation for RWDBExpr. RWDBExprFormDefinition allows a programmer to create an object that will translate into an RWDBExpr and eventually be expanded into an SQL string. The object will allow up to four expressions to be embedded into the resultant string.
An RWDBExprFormDefinition object is instantiated with a format string. The format string may contain place-holders for up to four positional parameters, which are labeled "%0" through "%3." An object defined in this way may subsequently be referenced in the same way that predefined functions like rwdbMax and rwdbAvg are referenced.
When an RWDBExprFormDefinition object is expanded by an RWDBExpr's asString() method, each instance of "%0" is replaced with the first actual argument, each instance of "%1" is replaced with the second actual argument, and so on. There can be multiple instances of a placeholder in the format string, and the placeholders may occur in any order. This allows great flexibility in defining functions, at the cost of losing compile-time checking on the number of arguments actually passed. To enable compile-time checking on number of actual arguments (at the cost of some flexibility), use the RWDBExprFuncDef<n> classes.
Return to Top of File.#include <rw/db/expr.h>
RWDBExpr represents expressions used in constructing SQL statements. It allows the SQL to be constructed using C++ syntax. Because there are several types of expressions, this class is simply an interface to a family of implementations that can represent numeric and string constants, columns from tables or other expressions. By its nature, an RWDBExpr can actually represent a complete complex expression in the form of a parse tree.
Because instances of this class are typically created anonymously, there are constructors taking the various operands used in expressions. These include the C++ primitive types, as well as the structured types used by DBtools.h++, such as RWCString and RWDBColumn.
RWDBExpr is designed around the Interface / Implementation paradigm. An RWDBExpr instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation.
Return to Top of File.#include <rw/db/inserter.h> RWDBInserter inserter = myTable.inserter(); RWDBInserter inserter = myTable.inserter(mySelector);
RWDBInserter is an encapsulation of the SQL "INSERT" statement. In SQL, the "INSERT" statement may be based either on a "VALUES" clause or on a "SELECT" statement. RWDBInserter supports either variant. Use the insertion operator (<<) to add items to an RWDBInserter's encapsulated "VALUES" clause, or supply an RWDBSelector when the RWDBInserter is produced. It is an error to insert into an RWDBInserter that was produced with an RWDBSelector.
RWDBInserters can be produced with an optional RWDBSchema, which is used to generate a list of column names. If the list of column names is given, the values are inserted one for one into the specified columns. Otherwise the values are inserted into the table columns in the order they were created.
RWDBInserter has a notion of the current position in itself. This position is set to zero when the RWDB Inserter is produced, and reset to zero whenever execute() is called. Each insertion operation adds a value at the current position and increments the position by one. If the RWDBInserter was created with an optional RWDBSchema then the indexing operators ([]) can set the position to a specified column, or column name and return a reference to self. DBtools.h++ does not check to see if values inserted match the table's schema in type or in number; such errors are reported by the database when execute() is invoked.
An "INSERT" statement does not normally produce results. However, DBtools.h++ recognizes that some database vendors provide triggers, which can cause results to be generated by an "INSERT" statement. Consequently, RWDBInserter 's execute() method returns an RWDBResult, which is a sequence of zero or more RWDBResultTables . Applications are not obliged to request any tables from the returned object.
RWDBInserter is designed around the Interface / Implementation paradigm. An RWDBInserter instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBInserter's implementation is a base class from which a family of database-specific inserter implementations is derived.
Return to Top of File.#include <rw/db/dbmgr.h>
RWDBDatabase myDb = RWDBManager::database("myDbType", "myDbServerName", "myLoginName", "myPassword", "myDbName");
There is a single, global RWDBManager in charge of producing RWDBDatabases typed according to the application's request. It mediates access to database servers, abstracting details of access to vendor-supplied libraries, including any dynamic loading and linking. The RWDBManager, through its database() method, is responsible for filling requests for database implementations of a particular type. To do so, it maintains a set of database types for which it is able to produce an implementation.
Associated with each database type is a method that produces the implementation. This method may reside in a dynamically-linked library, or may be statically linked with a specialized object. In the former case, the method is identified by a conventional name (rwdbNewDatabaseImp) with any ambiguity in the name is alleviated by the containing library. In the latter case, each method must be uniquely named ( for example, rwdbNewSybaseDatabaseImp ) and the association between method names and database types is made at link time via static initialization.
When presented with a request for a particular type of database implementation, the Manager consults its set of known implementations. If no entry is found, and the operating environment supports dynamic linking, a search is made for a dynamically-linked library whose name matches the requested type. If one is found, it is loaded, the conventionally-named method is located, and the association is added to the Manager's set of implementations. Once an entry is located, its method is invoked to obtain an implementation of the requested type, a connection is established, and the result is returned to the caller. If no entry is found, the object returned to the caller will have a status of RWDBStatus::notFound.
Return to Top of File.RWDBTable <-- RWDBMemTable
#include <rw/db/memtable.h>
RWDBMemTable myTable = myDb.memTable("myTable");
RWDBMemTable is a table of data that resides in program memory. After construction, an RWDBMemTable is no longer associated with a table in the database. An application may modify a RWDBMemTable's data as it sees fit. Such changes are not propagated back to the database.
RWDBMemTable is designed around the Interface / Implementation paradigm. An RWDBMemTable instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation.
Because an RWDBMemTable resides in memory, it is possible to provide random access to its data. DBtools.h++ provides an indexing operator ([ ]) for RWDBMemTable, the result of which is an RWDBRow. RWDBRow inherits an indexing operator ([ ]) from RWOrdered. The net result is the ability to access an RWDBMemTable's data with double indexing, as if it were a two-dimensional C++ array.
There are limitations when using RWDBMemTable, as not all functionality of a RWDBTable is available. The differences in functionality come from the lack of a "server" in memory for selecting, deleting, inserting, and updating memory tables through SQL constructs. This means that selectors, cursors, deleters, inserters, and updaters cannot be created using memory tables. Instead, the actual table in the database must be referenced.
However, RWDBReader may be produced from RWDBMemTable, allowing access to each row within the memory table, rather than using the indexing operators([ ]).
It should also be noted that since memory tables exist within memory, the normal data definition language (DDL) constructs that are associated with tables are also disfunctional, and return invalid results. These include grant , revoke, addColumn, dropColumn, etc.
Return to Top of File.#include <rw/db/nullind.h> RWDBNullIndicator nullInd;
RWDBNullIndicator provides a way for application code to determine whether a particular piece of data extracted from an RWDBReader is NULL. An RWDBNullIndicator instance may be interpreted as a boolean value: TRUE means a data item is NULL; FALSE means a data item is not NULL.
Return to Top of File.#include <rw/db/phrase.h> RWDBPhraseBook& phraseBook = myDbase.phraseBook();
RWDBPhraseBook serves as a lookup table for keywords and phrases used by specific databases. There is an RWDBPhraseBook associated with each RWDBDatabase instance. Internally, DBtools.h++ makes extensive use of this class to construct SQL from expressions.
Many DBtools.h++ objects (e.g. RWDBSelector) require an RWDBPhraseBook for their asString() method, so that they can generate SQL acceptable to a specific database. Applications wishing to call these asString() methods directly can obtain an RWDBPhraseBook from an RWDBDatabase.
#include <rw/db/reader.h> RWDBReader rdr = myTable.reader();
RWDBReader provides row-by-row access to tabular data. RWDBReaders are produced by RWDB Tables. When instantiated, an RWDBReader is positioned before the first row of the table which produced it. Subsequently, it can repeatedly advance to the next row, but can never retreat. The contents of each row, however, may be accessed at random. The function operator ( () ) is used to advance an RWDBReader one row. Within a row, the indexing ([ ]) and extraction (>>) operators may be used to access data.
The RWDBReader's extraction operator (>>) is used to transfer data from RWDBTables into program variables. DBtools.h++ has defined operator>> variants for all native C++ types, as well as for RWCString, RWDBDateTime, RWDecimalPortable (money), and RWDBBlob. Programmers are encouraged to define variants for classes in their application domain.
RWDBReader has a notion of the current position within the current row. Each time the reader is advanced to a new row, the position is set to 0. Each extraction increments the position by 1. The indexing operators ([ ]) set the position to a specified index, column, or column name; they return a reference to self, so that any of the following notations may be used:
reader >> x; reader[i] >> x; reader["columnName"] >> x; reader[table["columnName"]] >> x;
RWDBReader is designed around the Interface / Implementation paradigm. An RWDBReader instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBReader's implementation is a base class from which a family of database-specific reader implementations is derived.
Return to Top of File.#include <rw/db/result.h>
RWDBResult result = myDBase.executeSql("someSql");
RWDBResult result = mySelector.execute();
RWDBResult result = myInserter.execute();
RWDBResult result = myDeleter.execute();
RWDBResult result = myUpdater.execute();
RWDBResult result = myStoredProcedure.execute();
RWDBResult represents a sequence of zero or more RWDBResultTables. An RWDBResult instance is returned whenever a database operation may potentially produce multiple SQL "table expressions." This is most obviously the case when using the RWDBDatabase::executeSql() method to submit arbitrary SQL for execution. However, DBtools.h++ recognizes that some database vendors provide:
For this reason, each of the above execute() methods returns an RWDBResult instance. An application that knows that its database does not provide these capabilities is not obliged to check for multiple results.
Every RWDBResult instance has an RWDBConnection. Passing an RWDBConnection to an execute() method causes the RWDBResult to acquire the passed connection. Calling execute() without an RWDBConnection causes the RWDBResult to acquire a default connection from the caller's RWDBDatabase. In each case, the connection is held by the RWDBResult until the RWDBResult is destroyed.
The RWDBResultTables produced by RWDBResult must be processed in order. Each call to RWDBResult::table() causes unprocessed rows from any previous table to be flushed.
RWDBResult is designed around the Interface / Implementation paradigm. An RWDBResult instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBResult's implementation is a base class from which a family of database-specific result implementations is derived.
Return to Top of File.RWOrdered <-- RWDBRow
#include <rw/db/row.h> RWDBRow r = myMemTable[i];
RWDBRow is an ordered collection of RWDBValues. RWDBRow is a relatively low level construct used by DBtools.h++ to store a row of data on its way to or from the database. It visible to applications for two reasons:
The only semantics that RWDBRow adds to RWOrdered are:
#include <rw/db/schema.h> RWDBSchema s;
RWDBSchema is an ordered collection of RWDBColumns. As such, it serves as an encapsulation of the database notion of schema, a set of attributes defining a table. DBtools.h++ extends this notion slightly: an RWDBSchema is also used to define a stored procedure's formal parameter list, and to specify a list of columns wherever one is required.
Every RWDBTable has an RWDBSchema. An application can interrogate an RWDBTable's RWDBSchema for schema information, or can obtain a copy of an RWDBTable 's RWDBSchema for its own use. An RWDBSchema instance may be used to create a database table. To do this, an application can use an RWDBSchema obtained from an existing RWDBTable, modify an existing RWDBSchema, or build one from scratch using the appendColumn methods.
RWDBSchema is designed around the Interface / Implementation paradigm. An RWDBSchema instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation.
Return to Top of File. RWDBTable <--
RWDBSelector
RWDBSelectorBase <--
#include <rw/db/select.h> RWDBSelector select = myDatabase.selector();
RWDBSelector is an encapsulation of an SQL "SELECT" statement. Its methods provide an application with explicit control over the "SELECT" statement's select list, as well as its "FROM," "WHERE," "ORDER BY" and "GROUP BY" clauses. The set operators +, *, and - (union, intersection, and difference) may be applied to RWDBSelectors in order to achieve the semantics of the SQL "UNION," "INTERSECTION," and "DIFFERENCE" operations (see RWDBCompoundSelector). An RWDBSelector may be used to instantiate an RWDBExpr, so sub-selects are also supported.
The insertion operator (<<) is used to add items to an RWDBSelector's select list; the where() method is used to specify a "WHERE" clause. The items which are inserted into an RWDBSelector are RWDBExprs, which may be any combination of constants, column references, pre-defined functions, or RWDBSelectors combined by arithmetic or functional operators. The "WHERE" clause is encapsulated by an RWDBCriterion, which is some number of RWDBExprs combined with logical operators.
The result of an SQL "SELECT" statement is an SQL "table expression." DBtools.h++ represents this concept as a ResultTable. RWDBSelector is derived from RWDBTable so that applications can obtain an RWDBCursor or an RWDBReader directly from the RWDBSelector, without having to mention the intermediate result table explicitly. Hence, the following are equivalent:
(1) RWDBReader rdr = selector.execute().table().reader(); (2) RWDBReader rdr = selector.reader();
RWDBSelector also derives from RWDBSelectorBase so that RWDBSelector and RWDBCompoundSelector may be handled in a uniform manner.
RWDBSelector is designed around the Interface / Implementation paradigm. An RWDBSelector instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBSelector's implementation is a base class from which a family of database-specific selector implementations is derived.
Most RWDBSelector methods return a reference to self. This allows calls to be "stacked," as in
select.where(...).orderBy(...).groupBy(...), etc.Return to Top of File.
RWDBTable → RWDBSelectorBase
#include <rw/db/select.h>
RWDBSelectorBase is a base class from which RWDBSelector and RWDBCompoundSelector are derived. It encapsulates the features common to RWDBSelector and RWDBCompoundSelector.
RWDBSelectorBase provides no useful functionality on its own. Applications should treat it as though it were a pure virtual base class.
#include <rw/db/status.h> RWDBStatus status;
RWDBStatus encapsulates the error state of an object or operation. A valid object or a successful operation is represented by RWDBStatus::ok. An RWDBStatus that is not valid contains an error codee, an error message, and often some supplemental information provided by a database vendor's API. .
Each RWDBStatus object contains a callback routine that can be changed by an application. If an RWDB Status changes state to anything but RWDBStatus::ok, the installed handler is called with self as an argument.
In the DBtools.h++ error model, the use of exceptions is optional, and is under the application's control. The raise() method of RWDBStatus throws an exception of type RWExternalErr. Thus, an application may choose to enforce a terminating or non-terminating model of error handling by installing an appropriate error handler.
RWDBStatus obeys value semantics. When DBtools.h++ objects are produced by other objects, the produced object's status is copied from the producer. Consequently, an application can control error handling at any level it chooses. A handler installed in the RWDBManager is propagated to every DBtools.h++ object in the application; one installed in an RWDBDatabase is propagated to each object produced by that RWDBDatabase ; and so on down to the level of individual objects.
Return to Top of File.#include <rw/db/stored.h>
RWDBStoredProc myProc = myDbase.storedProc("myProcName");
Many modern RDBMS implementations include a mechanism to enforce database policy through stored procedures. Applications may be required to do much of their data manipulation through stored procedures. Unfortunately, the standards bodies have had little to say about stored procedures, so stored procedure implementations vary widely among RDBMS vendors. If an RWDBStoredProc feature is not supported by the underlying database, DBtools.h++ reports an RWDBStatus::notSupported error. The remainder of this section assumes that all features are supported. Check the DBtools.h++ access library documentation for information about what features are supported by a particular database.
RWDBStoredProc is an encapsulation of a database stored procedure. RWDBStoredProc supports creating and deleting stored procedures, retrieving stored procedures' definitions, executing stored procedures, and processing results returned from stored procedure execution. Parameters may be passed to an RWDBStoredProc prior to execution, and the values of output parameters may be retrieved. If a database vendor's stored procedure may return multiple sets of results, RWDBStoredProc can access each result set in turn.
RWDBStoredProc uses an RWDBSchema to store information about its formal parameters. Use the insertion operator (<<) to pass actual parameters to an RWDBStoredProc. Insert values if the stored procedure expects IN parameters; insert pointers if the stored procedure expects OUT or IN/OUT parameters and your application is interested in obtaining results through the parameters. Insert rwdbNull to pass a literal NULL by value. It is an error to insert a NULL pointer; if this occurs the RWDBStoredProc's status changes to RWDBStatus::nullReference.
RWDBStoredProc maintains a notion of the current position in its parameter list. The current position is set to zero when the RWDBStoredProc is created, and reset to zero whenever the RWDBStoredProc is executed. Each insertion of an actual parameter increments the current position by one. The indexing operator ([ ]) can be used to access a particular parameter position by number or by name. Given a stored procedure (myStoredProc) which expects the parameters "number" and "name" in that order, the following notations are equivalent:
myStoredProc << 1 << "Hello, world"; myStoredProc[0] << 1; myStoredProc[1] << "Hello, world"; myStoredProc["name"] << "Hello, world"; myStoredProc["number"] << 1;
RWDBStoredProc does not check actual parameters for type; it allows the database to do type conversion. If there is a type incompatibility, DBtools.h++ will pass along whatever the database reports to the application. DBtools.h++ will produce an RWDBStatus::invalidPosition error if too many arguments are inserted into an RWDBStoredProc. No check is made for "too few" arguments; the database may supply defaults. If not, DBtools.h++ will pass along whatever the database reports to the application.
In order to support parameter passing, DBtools.h++ uses a default connection to query the database for schema information whenever an RWDBStoredProc is produced by an RWDBDatabase.
RWDBStoredProc is designed around the Interface / Implementation paradigm. An RWDBStoredProc instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBStoredProc's implementation is a base class from which a family of database-specific selector implementations is derived.
Return to Top of File. RWDBTable <--
RWDBTMemTableBase <C> <-- RWTPtrMemTable <T, C>
C <--
#include <rw/db/tpmemtab.h> RWDBTPtrMemTable<T, C> mt;
This class represents a parameterized memory table. Not only can the type of the object inserted into the memory table be parameterized, but also the implementation.
Parameter T represents the type of the object to be stored in the memory table. It can be a class or a built in type. The class must have:
friend RWDBReader& operator>>(const RWDBReader&, const T&)
Parameter C represents the pointer based template collection that will be used as the implementation of the memory table. It must have:
Possible choices for C are the Tools.h++ classes RWTPtrSlist<T> and RWTPtrOrderedVector<T>.
The constructors for the class dynamically allocate space for the elements of type T that are placed in the collection. It is the application's responsiblity to free this memory when the RWDBTPtrMemTable goes out of scope. An effective way to do this is for the collection class C to call delete on each of its entries in its destructor.
Return to Top of File.#include <rw/db/table.h>
RWDBTable tableName = myDb.table("tableName");
RWDBTable tableName = myDb.memTable("tableName");
RWDBResult myResult = mySelecter.execute();
// or deleter.execute() or updater.execute() or
// storedProc.execute()
RWDBTable resultOfQuery = myResult.table();
RWDBTable is a base class from which a family of classes derive. RWDBTable represents a table of information whose actual location is transparent. The data may reside in a database table or in program memory, or may be an SQL "table expression," a collection of rows returned from a database query. The three kinds of tables to which RWDB Table provides an interface are:
RWDBTable is designed around the Interface / Implementation paradigm. An RWDBTable instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBTable's implementation is a base class from which a family of table implementations is derived. Each implementation except that of RWDBMemTable is in turn a base class from which a family of database-specific table implementations derive.
Return to Top of File.#include <rw/db/tracer.h>
#include <fstream.h>
ofstream strm("trace.trc");
RWDBTracer& tracer = myDbase.tracer();
tracer.setOn(RWDBTracer::SQL);
tracer.stream(strm);
RWDBTracer provides a runtime trace facility for DBtools.h++ applications. RWDBTracers can be turned on or off, and they can be told what to trace. The default output for an RWDBTracer is the stream clog. The output from an RWDBTracer can be redirected to an ostream.
DBtools.h++ classes which use the Interface / Implementation paradigm have an RWDBTracer in their implementation. A DBtools.h++ object that is produced by another DBtools.h++ object inherits the RWDB Tracer of its producer. Consequently, enabling tracing on an RWDBDatabase, for example, produces trace output for all objects produced by that RWDBDatabase.
It is the application's responsiblity to insure that the associated ostream referenced by the RWDBTracer remains in scope while the RWDBTracer is set on.
Return to Top of File.#include <rw/db/updater.h> RWDBUpdater updater = myTable.updater();
RWDBUpdater is an encapsulation of an SQL "UPDATE" statement. It's methods provide an application with explicit control over the "UPDATE" statement's "SET" and "WHERE" clauses.
The insertion operator (<<) is used to add encapsulated "SET" clauses to an RWDBUpdater; the where() method is used to specify a "WHERE" clause. The items which are inserted into an RWDBUpdater are RWDBAssignments, which are created by the assign() method of RWDBColumn. The "WHERE" clause is encapsulated by an RWDBCriterion, which is some number of RWDBExprs combined with logical operators.
An "UPDATE" statement does not normally produce results. However, DBtools.h++ recognizes that some database vendors provide triggers, which can cause results to be generated by an "UPDATE" statement. Consequently, RWDBUpdater 's execute() method returns an RWDBResult, which is a sequence of zero or more RWDBResultTables . Applications are not obliged to request any tables from the returned object.
RWDBUpdater is designed around the Interface / Implementation paradigm. An RWDBUpdater instance is an interface to a reference-counted implementation; copy constructors and assignment operators produce additional references to a shared implementation. An RWDBUpdater's implementation is a base class from which a family of database-specific updater implementations is derived.
Return to Top of File.RWCollectable <-- RWDBValue
#include <rw/db/value.h>
RWDBValue provides storage for C++ primitive types, and for structured types used by DBtools.h++. It also adds "Null / not Null" semantics to the primitive types. When DBtools.h++ fetches data from a database, it converts the data from the database vendor's data types into RWDBValues. When an application supplies DBtools.h++ with data, the data is stored as RWDBValues, so that the DBtools.h++ Access Libraries can standardize conversions from RWDBValue to a particular vendor's data types.
RWDBValue inherits class RWCollectable. The virtual functions of the base class RWCollectable have been redefined.
Return to Top of File.